Clock Managment Design

The design of this feature is based on Linux command of timedatectl.
(man page for timedatectl: https://man7.org/linux/man-pages/man1/timedatectl.1.html)

All set operations are based on this command, executing directly in linux upon user CLI execution. The time/date/timezone are configured directly to Linux, and is persistent upon any reboot.

System state of time/date/timezone will appear in 1 line as an output of existing "show clock" command.

hostcfgd will be the daemon in charge of this configuration management.

CLI Commands desin:

Set operations will be divided into 2 different commands:

1. config clock timezone <timezone> (to set timezone command)
	* will get single input as a string, and validate it is valid as part of ("timedatectl list-timezones" command).
	Validation will be done either by YANG model, or (if not possible) by issueing relevant error to log.
	* Value will be stored in db for future upgrade operations.
	Value is persistent upon reboot.
	* Linux timedatectl with set-timezone flag will be called.
	e.g. timedatectl set-timezone "Asia/Kolkata"
	* <b>In case NTP is enabled -> timezone configuration is allowed and overrides the current time.</b>
	* Date & timezone setting will be reflected of all the services/dockers in the system.


2. config clock date <YYYY-MM-DD> <HH:MM:SS> (to set time and date)
	* Command will recieve single string with date-time format <YYYY-MM-DD> <HH:MM:SS>
	* Command does not need to be stored in DB.
	* Linux timedatectl with set-time flag will be called.
	e.g. timedatectl set-time "2012-10-30 18:17:16"
	* <b>In case NTP is enabled -> time/date set is NOT allowed and being blocked</b>

Additional show command will be added to display all valid timezones:

3. show clock timezones

	* Will display list of all valid timezones to be configured.
	* based on "timedatectl list-timezones" linux command.

General notes:

* Both set commands will be written directly to Linux (via imedatectl command), and will be activated immediately.

* In case of any set command (time/date/timezone) a relevant message will be print to syslog.

* In case of any set command (time/date/timezone) - rsyslog service should be restarted to reflect the time change.

* Upgrades - timezone configuration is part of DEVICE_METADATA, hence - configuration upgrade will be taken care of as any other sonic configuration.

3 Configuration and management

3.1 ConfigDB Tables

Only timezone configuration will be saved. Additional field will be added to DEVICE_METADATA table

DEVICE_METADATA :{
    "timezone": {{string}}
}

default value: "Etc/UTC"

3.2 CLI/YANG model

3.2.1. Yang model

Adding to existing Yang model of device_metadata (https://github.com/sonic-net/sonic-buildimage/blob/master/src/sonic-yang-models/yang-models/sonic-device_metadata.yang)

    container sonic-device_metadata {

        container DEVICE_METADATA {

            description "DEVICE_METADATA part of config_db.json";

            container localhost{
			...
				leaf timezone {
					type string;
					description "System time-zone setting";
				}

3.2.2. CLI

Show CLI

root@host:~$ show clock 
Sun 15 Jan 2023 06:12:08 PM IST

root@host:~$ show clock timezones
Africa/Abidjan
Africa/Accra
Africa/Addis_Ababa
Africa/Algiers
Africa/Asmara
...

Config CLI

root@host:~$ config clock timezone "<timezone>"

root@host:~$ config clock date <YYYY-MM-DD> <HH:MM:SS>

4 Test Plan

4.1 Unit Test cases

Good flows:
a. set timezone -
output of the set command is empty, and expect to see the new timezone in show command output, and the time is correlated with this timezone.

b. set date & time -
- output of the set command is empty, and expect to see the new date & time in show command output.
c. check reboot -
rebooting without config save restores configuration (timezone) to the saved one.

d. check docker restart -
expect to see the time remains as system time.

e. config load / reload <> -
expect to see timezone changes upon new configuration.

f. reboot without config save -
expect rebooting without config save restores configuration (timezone) to the saved one.

g. upgrade with manually timedatectl before upgrade -
Expect to have configuration timezone (if configuration exist) apply and change the timedatectl.
Bad flows:
a. set invalid timezone -
expect for error message for invalid timezone, and timezone shouldn’t change (remains the same in show command output).

b. set empty string -
expect for error message for empty / incomplete command. Nothing should be changed after it.

c. set invalide date/time format -
expect for error message for the invalid parameter.
NTP interop
a. Change time/date, followed by changing NTP - and see time changed.
b. try to change time/date in case NTP is enabled -> and expect getting a failure.
c. Change timezone in case NTP is enabled, and expect to succeed and change relevant time.
Rsyslog:
a. In case of any set command (time/date/timezone) - verify rsyslog service should be restarted to reflect the time change.

Functional tests covering flows above will be part of sonic-mgmt tests suite.

Larch SONiC Documentation

Clock Managment Design

Table of Content

1.1 Revision

1.2. Scope

1.3 Definitions/Abbreviations

1.4 Overview

1.5 Requirements

1.5.1. Functional requirements

1.5.2. Configuration and Management Requirements

2 Design

2.1 High-Level Design